home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / catn / checkbutton.n < prev    next >
Text File  |  1994-09-20  |  13KB  |  331 lines
  1.  
  2.  
  3.  
  4. checkbutton(n)             Tk Commands
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      checkbutton - Create and manipulate check-button widgets
  12.  
  13. SYNOPSIS
  14.      checkbutton _p_a_t_h_N_a_m_e ?_o_p_t_i_o_n_s?
  15.  
  16. STANDARD OPTIONS
  17.      activeBackground               bitmap          fontrelief     |
  18.      activeForeground               borderWidth     foregroundtext |
  19.      anchor          cursor         padX            textVariable   |
  20.      background      disabledForeground             padY           |
  21.  
  22.      See the ``options'' manual entry for details on the standard
  23.      options.
  24.  
  25. WIDGET-SPECIFIC OPTIONS
  26.      Name:           command
  27.      Class:          Command
  28.      Command-Line Switch:-command
  29.  
  30.           Specifies a Tcl command to associate with  the  button.
  31.           This  command  is typically invoked when mouse button 1
  32.           is released over the button window.  The button's  glo-
  33.           bal  variable (-variable option) will be updated before
  34.           the command is invoked.
  35.  
  36.      Name:           height                                        |
  37.      Class:          Height                                        |
  38.      Command-Line Switch:-height                                   |
  39.  
  40.                                                                         ||
  41.           Specifies a desired height for the button.  If a bitmap  |
  42.           is being displayed in the button then the value  is  in  |
  43.           screen  units  (i.e.  any  of  the  forms acceptable to  |
  44.           Tk_GetPixels); for text it is in  lines  of  text.   If  |
  45.           this  option  isn't  specified,  the  button's  desired  |
  46.           height is computed from the size of the bitmap or  text  |
  47.           being displayed in it.
  48.  
  49.      Name:           offValue
  50.      Class:          Value
  51.      Command-Line Switch:-offvalue
  52.  
  53.           Specifies value to store  in  the  button's  associated
  54.           variable  whenever this button is deselected.  Defaults
  55.           to ``0''.
  56.  
  57.      Name:           onValue
  58.      Class:          Value
  59.      Command-Line Switch:-onvalue
  60.  
  61.  
  62.  
  63. Tk                                                              1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. checkbutton(n)             Tk Commands
  71.  
  72.  
  73.  
  74.           Specifies value to store  in  the  button's  associated
  75.           variable whenever this button is selected.  Defaults to
  76.           ``1''.
  77.  
  78.      Name:           selector
  79.      Class:          Foreground
  80.      Command-Line Switch:-selector
  81.  
  82.           Specifies the color to draw in the selector  when  this
  83.           button  is  selected.   If specified as an empty string  |
  84.           then no selector is drawn for the button.                |
  85.  
  86.      Name:           state                                         |
  87.      Class:          State                                         |
  88.      Command-Line Switch:-state                                    |
  89.  
  90.                                                                         ||
  91.           Specifies  one  of  three  states for the check button:  |
  92.           normal, active, or disabled.  In normal state the check  |
  93.           button is displayed using the foreground and background  |
  94.           options.  The active state is typically used  when  the  |
  95.           pointer  is over the check button.  In active state the  |
  96.           check button is displayed  using  the  activeForeground  |
  97.           and  activeBackground  options.   Disabled  state means  |
  98.           that the  check  button  is  insensitive:   it  doesn't  |
  99.           activate  and  doesn't respond to mouse button presses.  |
  100.           In this state  the  disabledForeground  and  background  |
  101.           options determine how the check button is displayed.
  102.  
  103.      Name:           variable
  104.      Class:          Variable
  105.      Command-Line Switch:-variable
  106.  
  107.           Specifies name of global variable to  set  to  indicate
  108.           whether  or  not  this button is selected.  Defaults to
  109.           the name of the button within its parent (i.e. the last
  110.           element of the button window's path name).
  111.  
  112.      Name:           width                                         |
  113.      Class:          Width                                         |
  114.      Command-Line Switch:-width                                    |
  115.  
  116.                                                                         ||
  117.           Specifies  a desired width for the button.  If a bitmap  |
  118.           is being displayed in the button then the value  is  in  |
  119.           screen  units  (i.e.  any  of  the  forms acceptable to  |
  120.           Tk_GetPixels); for text it is in characters.   If  this  |
  121.           option  isn't  specified, the button's desired width is  |
  122.           computed from the size of  the  bitmap  or  text  being  |
  123.           displayed in it.
  124. _________________________________________________________________
  125.  
  126.  
  127.  
  128.  
  129. Tk                                                              2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. checkbutton(n)             Tk Commands
  137.  
  138.  
  139.  
  140. DESCRIPTION
  141.      The checkbutton command creates a new window (given  by  the
  142.      _p_a_t_h_N_a_m_e  argument) and makes it into a check-button widget.
  143.      Additional options, described above, may be specified on the
  144.      command  line or in the option database to configure aspects
  145.      of the check button such as its colors, font, text, and ini-
  146.      tial  relief.   The checkbutton command returns its _p_a_t_h_N_a_m_e
  147.      argument.  At the time this command is invoked,  there  must
  148.      not  exist  a  window  named _p_a_t_h_N_a_m_e, but _p_a_t_h_N_a_m_e's parent
  149.      must exist.
  150.  
  151.      A check button is a widget that displays a textual string or  |
  152.      bitmap  and  a square called a _s_e_l_e_c_t_o_r.  A check button has  |
  153.      all of the behavior of a simple button, including  the  fol-  |
  154.      lowing:  it  can display itself in either of three different  |
  155.      ways, according to the state  option;  it  can  be  made  to
  156.      appear raised, sunken, or flat; it can be made to flash; and
  157.      it invokes a Tcl command whenever mouse button 1 is  clicked
  158.      over the check button.
  159.  
  160.      In addition, check buttons can be _s_e_l_e_c_t_e_d.  If a check but-
  161.      ton  is  selected  then  a  special highlight appears in the
  162.      selector, and a Tcl variable associated with the check  but-
  163.      ton is set to a particular value (normally 1).  If the check
  164.      button is not selected, then the selector is drawn in a dif-
  165.      ferent  fashion and the associated variable is set to a dif-
  166.      ferent value (typically 0).  By default,  the  name  of  the
  167.      variable  associated  with a check button is the same as the
  168.      _n_a_m_e used to create the check button.   The  variable  name,
  169.      and the ``on'' and ``off'' values stored in it, may be modi-
  170.      fied with options on the command line or in the option data-
  171.      base.  By default a check button is configured to select and
  172.      deselect itself on alternate button  clicks.   In  addition,  |
  173.      each  check  button  monitors  its  associated  variable and  |
  174.      automatically selects and deselects itself  when  the  vari-  |
  175.      ables value changes to and from the button's ``on'' value.
  176.  
  177.  
  178. WIDGET COMMAND
  179.      The checkbutton command creates a new Tcl command whose name
  180.      is  _p_a_t_h_N_a_m_e.   This  command  may be used to invoke various
  181.      operations on the widget.   It  has  the  following  general
  182.      form:
  183.  
  184.           _p_a_t_h_N_a_m_e _o_p_t_i_o_n ?_a_r_g _a_r_g ...?
  185.  
  186.      _O_p_t_i_o_n and the _a_r_gs determine the exact behavior of the com-
  187.      mand.   The following commands are possible for check button
  188.      widgets:
  189.  
  190.      _p_a_t_h_N_a_m_e activate
  191.           Change the check button's state to active and redisplay
  192.           the  button  using its active foreground and background
  193.  
  194.  
  195.  
  196. Tk                                                              3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. checkbutton(n)             Tk Commands
  203.  
  204.  
  205.  
  206.           colors instead  of  normal  colors.   This  command  is  |
  207.           ignored  if the check button's state is disabled.  This  |
  208.           command is obsolete and will eventually be removed; use  |
  209.           ``_p_a_t_h_N_a_m_e configure -state active'' instead.
  210.  
  211.      _p_a_t_h_N_a_m_e configure ?_o_p_t_i_o_n? ?_v_a_l_u_e _o_p_t_i_o_n _v_a_l_u_e ...?
  212.           Query  or  modify  the  configuration  options  of  the
  213.           widget.   If  no  _o_p_t_i_o_n  is  specified, returns a list
  214.           describing all of the available  options  for  _p_a_t_h_N_a_m_e
  215.           (see  Tk_ConfigureInfo for information on the format of
  216.           this list).  If _o_p_t_i_o_n is specified with no _v_a_l_u_e, then
  217.           the  command  returns  a  list describing the one named
  218.           option (this list will be identical to the  correspond-
  219.           ing  sublist  of  the  value  returned  if no _o_p_t_i_o_n is
  220.           specified).  If one  or  more  _o_p_t_i_o_n-_v_a_l_u_e  pairs  are
  221.           specified,  then  the command modifies the given widget
  222.           option(s) to have the given value(s);  in this case the
  223.           command  returns  an empty string.  _O_p_t_i_o_n may have any
  224.           of the values accepted by the checkbutton command.
  225.  
  226.      _p_a_t_h_N_a_m_e deactivate
  227.           Change the check button's state to normal and redisplay
  228.           the  button  using its normal foreground and background
  229.           colors.  This command is ignored if the check  button's  |
  230.           state  is  disabled.  This command is obsolete and will  |
  231.           eventually be removed; use ``_p_a_t_h_N_a_m_e configure  -state  |
  232.           normal'' instead.
  233.  
  234.      _p_a_t_h_N_a_m_e deselect
  235.           Deselect the check  button:   redisplay  it  without  a
  236.           highlight  in the selector and set the associated vari-
  237.           able to its ``off'' value.
  238.  
  239.      _p_a_t_h_N_a_m_e flash
  240.           Flash  the  check  button.   This  is  accomplished  by
  241.           redisplaying  the check button several times, alternat-
  242.           ing between active and normal colors.  At  the  end  of
  243.           the  flash  the  check  button  is  left  in  the  same
  244.           normal/active state as when the  command  was  invoked.  |
  245.           This  command is ignored if the check button's state is  |
  246.           disabled.
  247.  
  248.      _p_a_t_h_N_a_m_e invoke
  249.           Does just what would have happened if the user  invoked  |
  250.           the  check  button with the mouse: toggle the selection  |
  251.           state of the button and invoke the Tcl command  associ-  |
  252.           ated  with  the  check  button,  if  there is one.  The  |
  253.           return value is the return value from the Tcl  command,  |
  254.           or  an  empty  string if there is no command associated  |
  255.           with the check button.  This command is ignored if  the  |
  256.           check button's state is disabled.
  257.  
  258.  
  259.  
  260.  
  261. Tk                                                              4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. checkbutton(n)             Tk Commands
  269.  
  270.  
  271.  
  272.      _p_a_t_h_N_a_m_e select
  273.           Select the check button:  display it with a highlighted
  274.           selector  and set the associated variable to its ``on''
  275.           value.
  276.  
  277.      _p_a_t_h_N_a_m_e toggle
  278.           Toggle the selection state of the button,  redisplaying
  279.           it and modifying its associated variable to reflect the
  280.           new state.
  281.  
  282.  
  283. BINDINGS
  284.      Tk automatically creates class bindings  for  check  buttons  |
  285.      that give them the following default behavior:                |
  286.  
  287.      [1]                                                                ||
  288.           The  check  button  activates whenever the mouse passes  |
  289.           over it and deactivates whenever the mouse  leaves  the  |
  290.           check button.                                            |
  291.  
  292.      [2]                                                                ||
  293.           The check button's relief is changed to sunken whenever  |
  294.           mouse button 1 is pressed over it, and  the  relief  is  |
  295.           restored  to  its original value when button 1 is later  |
  296.           released.                                                |
  297.  
  298.      [3]                                                                ||
  299.           If  mouse button 1 is pressed over the check button and  |
  300.           later released over the check button, the check  button  |
  301.           is  invoked  (i.e.  its selection state toggles and the  |
  302.           command associated with the button is invoked, if there  |
  303.           is  one).   However, if the mouse is not over the check  |
  304.           button when button 1 is released,  then  no  invocation  |
  305.           occurs.                                                  |
  306.  
  307.      If the check button's state is disabled  then  none  of  the  |
  308.      above  actions  occur:   the check button is completely non-  |
  309.      responsive.                                                   |
  310.  
  311.      The behavior of check buttons can be changed by defining new  |
  312.      bindings  for  individual widgets or by redefining the class  |
  313.      bindings.
  314.  
  315.  
  316. KEYWORDS
  317.      check button, widget
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327. Tk                                                              5
  328.  
  329.  
  330.  
  331.